<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>find</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_001_014_738">&nbsp;</a>NAME</h4><blockquote>
find - find files
</blockquote><h4><a name = "tag_001_014_739">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

find <i>path</i>... <b>[</b><i>operand_expression</i><b>]</b>
</code>
</pre>
</blockquote><h4><a name = "tag_001_014_740">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>find</i>
utility will recursively descend the directory hierarchy from
each file specified by
<i>path</i>,
evaluating a Boolean expression composed of the primaries described in
the OPERANDS section for each file encountered.
<p>
The
<i>find</i>
utility will be able to descend to arbitrary depths
in a file hierarchy and will not fail due to path length
limitations (unless a
<i>path</i>
operand specified by the application exceeds
{PATH_MAX}
requirements).
</blockquote><h4><a name = "tag_001_014_741">&nbsp;</a>OPTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_742">&nbsp;</a>OPERANDS</h4><blockquote>
The following operands are supported:
<p>
The
<i>path</i>
operand is a pathname of a starting point in the directory hierarchy.
<p>
The first argument that starts with a "-", or is a "!" or a "(",
and all subsequent arguments will be interpreted as an
<i>expression</i>
made up of the following primaries and operators.
In the descriptions, wherever
<i>n</i>
is used as a primary argument, it will be interpreted as a
decimal integer optionally preceded by a plus
(+)
or minus
(-)
sign, as follows:
<dl compact>

<dt><b>+</b><i>n</i><dd>more than
<i>n</i>

<dt><i>n</i><dd>exactly
<i>n</i>

<dt><b>-</b><i>n</i><dd>less than
<i>n</i>.

</dl>
<p>
The following primaries are supported:
<dl compact>
<dt><b>-name&nbsp;</b><i>pattern</i>
<dd>
The primary will evaluate as true
if the basename of the
filename being examined matches
<i>pattern</i>
using the pattern matching notation described in
<a href="chap2.html#tag_001_013">
Pattern Matching Notation
</a>
<dt><b>-nouser</b>
<dd>The primary will evaluate as true
if the file belongs to a user ID for which the <b>XSH</b> specification
<i><a href="../xsh/getpwuid.html">getpwuid()</a></i>
(or equivalent) function returns NULL.
<dt><b>-nogroup</b>
<dd>
The primary will evaluate as true
if the file belongs to a group ID for which the <b>XSH</b> specification
<i><a href="../xsh/getgrgid.html">getgrgid()</a></i>
(or equivalent) function returns NULL.
<dt><b>-xdev</b>
<dd>The primary always will evaluate as true; it will cause
<i>find</i>
not to continue descending past directories that have a different
device ID
(<i>st_dev</i>,
see the <b>XSH</b> specification
<i><a href="../xsh/stat.html">stat()</a></i>
function).
If any
<b>-xdev</b>
primary is specified, it will apply to the entire
expression even if the
<b>-xdev</b>
primary would not normally be evaluated.
<dt><b>-prune</b>
<dd>The primary always will evaluate as true; it will cause
<i>find</i>
not to descend the current pathname if it is a directory.
If the
<b>-depth</b>
primary is specified, the
<b>-prune</b>
primary will have no effect.

<dt><b>-perm&nbsp;[-]</b><i>mode</i><dd>
The
<i>mode</i>
argument is used to represent file mode bits.
It will be identical in format to the
<i>symbolic_mode</i>
operand described in
<a href="chmod.html#tag_001_014">
Special Built-in Utilities
</a>
and will be interpreted as follows.
To start, a template will be assumed with all file mode bits cleared.
An
<i>op</i>
symbol of "+" will set the appropriate mode bits in the template;
"-" will clear the appropriate bits; "="
will set the appropriate mode bits, without regard
to the contents of process' file mode creation mask.
The
<i>op</i>
symbol of "-" cannot be the first character of
<i>mode</i>;
this avoids ambiguity with the optional leading hyphen.
Since the initial mode is all bits off, there are not any
symbolic modes that need to use "-" as the first character.

If the hyphen is omitted, the primary will evaluate as
true when the file permission bits exactly match
the value of the resulting template.

Otherwise, if
<i>mode</i>
is prefixed by a hyphen, the primary will evaluate as true
if at least all the bits in the resulting template are set
in the file permission bits.

<dt><b>-perm&nbsp;[-]</b><i>onum</i><dd>
If the hyphen is omitted, the primary will evaluate as
true when the file permission bits exactly match
the value of the octal number
<i>onum</i>
and only the bits corresponding to the octal mask
07777 will be compared.
(See the description of the octal
<i>mode</i>
in
<i><a href="chmod.html">chmod</a></i>.)
Otherwise, if
<i>onum</i>
is prefixed by a hyphen,
the primary will evaluate as true
if at least all of the bits specified in
<i>onum</i>
that are also set in the octal mask 07777 are set.
<dt><b>-type&nbsp;</b><i>c</i>
<dd>The primary will evaluate as true
if the type of the file is
<i>c</i>,
where
<i>c</i>
is
b,
c,
d,
p
or
f
for block special file, character special file,
directory, FIFO or regular file, respectively.
<dt><b>-links&nbsp;</b><i>n</i>
<dd>
The primary will evaluate as true
if the file has
<i>n</i>
links.
<dt><b>-user&nbsp;</b><i>uname</i>
<dd>
The primary will evaluate as true
if the file belongs to the user
<i>uname.</i>
If
<i>uname</i>
is a decimal integer
and the
<i><a href="../xsh/getpwnam.html">getpwnam()</a></i>
(or equivalent) function does not return
a valid user name,
<i>uname</i>
will be interpreted as a user ID.
<dt><b>-group&nbsp;</b><i>gname</i>
<dd>
The primary will evaluate as true
if the file belongs to the group
<i>gname</i>.
If
<i>gname</i>
is a decimal integer and the
<i><a href="../xsh/getgrnam.html">getgrnam()</a></i>
(or equivalent) function does not return
a valid group name,
<i>gname</i>
will be interpreted as a group ID.

<dt><b>-size&nbsp;</b><i>n</i><b>[c]</b><dd>
The primary will evaluate as true
if the file size in bytes,
divided by
512 and rounded up to the next integer, is
<i>n</i>.
If
<i>n</i>
is followed by the character
c,
the size will be in bytes.
<dt><b>-atime&nbsp;</b><i>n</i>
<dd>
The primary will evaluate as true
if the file access time subtracted from the
initialisation time is
<i>n</i>-1
to
<i>n</i>
multiples of 24 hours.
The initialisation time will be a time between the invocation of the
<i>find</i>
utility and the first access by that invocation of the
<i>find</i>
utility to any file specified by its
<i>path</i>
operands.
For example,
<b>-atime</b>
3
is true if the file was accessed any time in the period
from 72 to 48 hours ago.
<dt><b>-mtime&nbsp;</b><i>n</i>
<dd>
The primary will evaluate as true
if the file modification time subtracted from the
initialisation time is
<i>n</i>-1
to
<i>n</i>
multiples of 24 hours.
The initialisation time will be a time between the invocation of the
<i>find</i>
utility and the first access by that invocation of the
<i>find</i>
utility to any file specified by its
<i>path</i>
operands.
<dt><b>-ctime&nbsp;</b><i>n</i>
<dd>
The primary will evaluate as true
if the time of last change of file status information
subtracted from the
initialisation time is
<i>n</i>-1
to
<i>n</i>
multiples of 24 hours.
The initialisation time will be a time between the invocation of the
<i>find</i>
utility and the first access by that invocation of the
<i>find</i>
utility to any file specified by its
<i>path</i>
operands.

<dt><b>-exec </b><i>utility_name </i><b>[</b><i>argument&nbsp;...</i><b>]&nbsp;;</b><dd>
The primary will evaluate as true
if the invoked utility
<i>utility_name</i>
returns a zero value as exit status.
The end of the primary expression
will be punctuated by a semicolon.
A
<i>utility_name</i>
or
<i>argument</i>
containing only the two characters
{}
will be replaced by the current pathname.
If a
<i>utility_name</i>
or argument string contains the two characters
{},
but not just the two characters
{},
it is implementation-dependent
whether
<i>find</i>
replaces those two characters with the
current pathname or uses the string without change.
The current directory for the invocation of
<i>utility_name</i>
will be the same as the current directory when the
<i>find</i>
utility was started.
If the
<i>utility_name</i>
names any of the special built-in utilities in
<a href="chap2.html#tag_001_014">
Special Built-in Utilities
</a>,
the results are undefined.

<dt><b>-ok&nbsp;</b><i>utility_name&nbsp;</i><b>[</b><i>argument&nbsp;...</i><b>]&nbsp;;</b><dd>
The
<b>-ok</b>
primary will be equivalent to
<b>-exec</b>,
except that
<i>find</i>
will request affirmation of the invocation of
<i>utility_name</i>
using the current file as an argument
by writing to standard error as described in the STDERR section.
If the response on standard input is affirmative,
the utility will be invoked.
Otherwise, the command will not be invoked
and the value of the
<b>-ok</b>
operand will be false.
<dt><b>-print</b>
<dd>The primary always will evaluate as true; it will cause
the current pathname to be written to standard output.
<dt><b>-newer&nbsp;</b><i>file</i>
<dd>
The primary will evaluate as true
if the modification time of the current file
is more recent than the modification time of the
file named by the pathname
<i>file</i>.
<dt><b>-depth</b>
<dd>The primary always will evaluate as true; it will cause
descent of the directory hierarchy to be done
so that all entries in a directory are acted on
before the directory itself.
If a
<b>-depth</b>
primary is not specified, all entries in a directory
will be acted on after the directory itself.
If any
<b>-depth</b>
primary
is specified, it will apply to the entire expression even if the
<b>-depth</b>
primary would not normally be evaluated.

</dl>
<p>
The primaries can be combined using the following operators
(in order of decreasing precedence):
<dl compact>

<dt>(<dd>
True if
<i>expression</i>
is true.

<dt><b>! </b><i>expression</i><dd>
Negation of a primary; the unary NOT operator.

<dt><i>expression&nbsp;</i><b>[-a]&nbsp;</b><i>expression</i><dd>
Conjunction of primaries; the AND
operator will be implied by the juxtaposition
of two primaries or made explicit by the optional
<b>-a</b>
operator.
The second expression will not be evaluated if the first
expression is false.

<dt><i>expression </i><b>-o </b><i>expression</i><dd>
Alternation of primaries; the OR operator.
The second expression will not be evaluated if
the first expression is true.

</dl>
<p>
If no
<i>expression</i>
is present,
<b>-print</b>
will be used as the expression.
Otherwise, if the given expression does not contain
any of the primaries
<b>-exec</b>,
<b>-ok</b>
or
<b>-print</b>,
the given expression will be effectively replaced by:
<pre>
<code>
( <i>given_expression</i> ) -print
</code>
</pre>
<p>
The
<b>-user</b>,
<b>-group</b>
and
<b>-newer</b>
primaries each will evaluate their respective arguments only once.
</blockquote><h4><a name = "tag_001_014_743">&nbsp;</a>STDIN</h4><blockquote>
If the
<b>-ok</b>
primary is used, the response will be read from the standard input.
An entire line will be read as the response.
Otherwise, the standard input will not be used.
</blockquote><h4><a name = "tag_001_014_744">&nbsp;</a>INPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_745">&nbsp;</a>ENVIRONMENT VARIABLES</h4><blockquote>
The following environment variables affect the execution of
<i>find</i>:
<dl compact>

<dt><i>LANG</i><dd>Provide a default value for the internationalisation variables
that are unset or null.
If
<i>LANG</i>
is unset or null, the corresponding value from the
implementation-dependent default locale will be used.
If any of the internationalisation variables contains an invalid setting, the
utility will behave as if none of the variables had been defined.

<dt><i>LC_ALL</i><dd>
If set to a non-empty string value,
override the values of all the other internationalisation variables.

<dt><i>LC_COLLATE</i><dd>
Determine the locale for the
behaviour of ranges, equivalence classes
and multi-character collating elements
used in the pattern matching notation for the
<b>-n</b>
option and in the extended regular expression defined for the
<b>yesexpr</b>
locale keyword in the LC_MESSAGES category.

<dt><i>LC_CTYPE</i><dd>
This variable will determine the
locale for the interpretation of sequences of bytes of text data as
characters (for example, single-
versus multi-byte characters in arguments),
the behaviour of character classes within
the pattern matching notation used for the
<b>-n</b>
option,
and the behaviour of character classes within
regular expressions
used in the extended regular expression defined for the
<b>yesexpr</b>
locale keyword in the LC_MESSAGES category.

<dt><i>LC_MESSAGES</i><dd>
Determine the locale for the processing of affirmative responses
that should be used to affect the format and contents of diagnostic
messages written to standard error.

<dt><i>NLSPATH</i><dd>
Determine the location of message catalogues
for the processing of
<i>LC_MESSAGES .
</i>
<dt><i>PATH</i><dd>Determine the location of the
<i>utility_name</i>
for the
<b>-exec</b>
and
<b>-ok</b>
primaries, as described in
the <b>XBD</b> specification, <a href="../xbd/envvar.html"><b>Environment Variables</b>&nbsp;</a> .

</dl>
</blockquote><h4><a name = "tag_001_014_746">&nbsp;</a>ASYNCHRONOUS EVENTS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_747">&nbsp;</a>STDOUT</h4><blockquote>
The
<b>-print</b>
primary will cause the current pathnames to be written to standard output.
The format will be:
<p><code>
<tt>"%s\n"</tt>, &lt;<i>path</i>&gt;
</code>
</blockquote><h4><a name = "tag_001_014_748">&nbsp;</a>STDERR</h4><blockquote>
The
<b>-ok</b>
primary
will write a prompt to standard error containing at least the
<i>utility_name</i>
to be invoked and the current pathname.
In the POSIX locale, the last
non-blank character in the prompt will be
"?".
The exact format used is unspecified.
<p>
Otherwise, the standard error will be used only for diagnostic messages.
</blockquote><h4><a name = "tag_001_014_749">&nbsp;</a>OUTPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_750">&nbsp;</a>EXTENDED DESCRIPTION</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_751">&nbsp;</a>EXIT STATUS</h4><blockquote>
The following exit values are returned:
<dl compact>

<dt>0<dd>All
<i>path</i>
operands were traversed successfully.

<dt>&gt;0<dd>An error occurred.

</dl>
</blockquote><h4><a name = "tag_001_014_752">&nbsp;</a>CONSEQUENCES OF ERRORS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_753">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
When used in operands,
pattern matching notation,
semicolons, opening parentheses, and closing parentheses are
special to the shell and must be quoted (see
<a href="chap2.html#tag_001_002">
Quoting
</a>).
<p>
The bit that is traditionally used for sticky (historically 01000)
is still specified in the
<b>-perm</b>
primary using the octal number argument form.
Since this bit is not defined by this specification,
applications must not assume that it actually refers
to the traditional sticky bit.
<p>
The references to octal modes are marked EX
because, although they are obsolescent in the ISO/IEC 9945-2:1993 standard,
The Open Group is committed to maintaining them
for portable applications until further notice.
</blockquote><h4><a name = "tag_001_014_754">&nbsp;</a>EXAMPLES</h4><blockquote>
<ol>
<li>
The following commands are equivalent:
<pre>
<code>
find .
find . -print
</code>
</pre>
They both write out the entire directory hierarchy from the current directory.
<p>
<li>
The following command:
<pre>
<code>
find / \( -name tmp -o -name '*.xx' \) -atime +7 -exec rm {} \;
</code>
</pre>
removes all files named
<b>tmp</b>
or ending in
.xx
that have not been accessed for seven
or more 24-hour periods.
<p>
<li>
The following command:
<pre>
<code>
find . -perm -o+w,+s
</code>
</pre>
prints
(<b>-print</b>
is assumed) the names of all files in or below the
current directory, with all of the file permission bits
S_ISUID, S_ISGID and S_IWOTH set.
<p>
<li>
The following command:
<pre>
<code>
find . -name SCCS -prune -o -print
</code>
</pre>
recursively prints pathnames of all files in the current
directory and below, but skips directories named SCCS and
files in them.
<p>
<li>
The following command:
<pre>
<code>
find . -print -name SCCS -prune
</code>
</pre>
behaves as in the previous example, but prints the names of the
SCCS directories.
<br>
<p>
<li>
The following command is roughly equivalent to the
<b>-nt</b>
extension to
<i><a href="test.html">test</a></i>:
<pre>
<code>
if [ -n "$(find file1 -prune -newer file2)" ]; then
    printf %s\\n "file1 is newer than file2"
fi
</code>
</pre>
<p>
<li>
The descriptions of
<b>-atime</b>,
<b>-ctime</b>
and
<b>-mtime</b>
use the terminology
<i>n</i>
&quot;24-hour periods&quot;.
For example, a file accessed at
23:59 will be selected by:
<pre>
<code>
find . -atime -1 -print
</code>
</pre>
at 00:01 the next day (less than 24 hours later, not
more than one day ago); the midnight boundary between
days has no effect on the 24-hour calculation.
<p>
</ol>
</blockquote><h4><a name = "tag_001_014_755">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
The IEEE PASC 1003.2 Interpretations Committee has forwarded concerns about 
parts of this interface definition to the IEEE PASC Shell and Utilities Working Group
which is identifying the corrections.
A future revision of this specification will align with
IEEE Std. 1003.2b when finalised.
</blockquote><h4><a name = "tag_001_014_756">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="chmod.html">chmod</a></i>,
<i><a href="pax.html">pax</a></i>,
<i><a href="sh.html">sh</a></i>,
<i><a href="test.html">test</a></i>,
the <b>XSH</b> specification description of
<i><a href="../xsh/stat.html">stat()</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
